/***************************************************************
*  Copyright (c) 2007 by GroupMe! Team (www.groupme.net)
*  All rights reserved.
*
*  This file is part of the GroupMe! Project. Source code of 
*  this project is closed and redistribution of this code is
*  prohibited. 
*  
*  Contact: http://www.groupme.net
*
*  This copyright notice MUST APPEAR in all copies of the file!
***************************************************************/
package net.groupme.search.strategy;

import java.util.List;
import java.util.Map;

import net.groupme.model.Resource;
import net.groupme.model.Tag;
import net.groupme.search.strategy.model.WeightedGroup;
import net.groupme.search.strategy.model.WeightedResource;

/**
 * created on Jul 4, 2007
 * 
 * This interafce methods that are used to determine a scoring
 * of a resource according to a tag and the resource-context (which
 * may be the groups the resource is involved in,...).
 * 
 * @author Fabian Abel, <a href="mailto:abel@l3s.de">abel@l3s.de</a>
 * @author last edited by: $Author: fabian $
 * 
 * @version $Revision: 1.2 $ $Date: 2007-07-04 13:16:57 $
 */
public interface ScoringStrategy {

	/**
	 * Returns the scoring value of the resource according to its context (= group, user,..).
	 * Thus: How related is the context of the given resource to the given tag?
	 * 
	 * @param resource the resource for which the scoring value should be computed
	 * @param tag the tag which is the basement for the score
	 * @return the score which should be between 0..1
	 */
	public double computeResourceContextScore(Resource resource, Tag tag);
	
	/**
	 * Evaluates the overall scoring value of the resource's context.
	 * 
	 * @param groupResourceMapping mapping from {@link WeightedGroup} instances (weighted among user tagging) to 
	 * list of {@link WeightedResource} instances (each list corresponds to the memebers of a group).
	 * 
	 * @return list of {@link WeightedResource} instances (thus a mapping from resources to scoring values (= 0..1))
	 */
	public List<WeightedResource> computeOverallContextScore(Map<WeightedGroup, List<WeightedResource>> groupResourceMapping);
	
	/**
	 * Combines the direct scoring value of a resource with the scoring value of the
	 * context:
	 * <pre>
	 * score = a * directScoreOfResource + b * contextScoreOfResource
	 * </pre>
	 * Parameters a, b can be adjusted.
	 * 
	 * @param directResourceScoring mapping from resources to direct scoring values (= 0..1)
	 * @param contextScoring mapping from resources to context scoring values (= 0..1)
	 * @return unsorted list of {@link WeightedResource} instances 
	 */
	public List<WeightedResource> combineScorings(List<WeightedResource>  directResourceScoring, List<WeightedResource> contextScoring);
}
